GetMenu

GetMenu
Header:	Menus.h		Carbon status:	Supported

Creates a menu from the specified menu and extended menu resources.

MenuRef GetMenu (
    SInt16 resourceID
);

resourceID: The resource ID of the menu and extended menu that defines the characteristics of the menu. You typically use the same number for a menu’s resource ID as the number that you specify for the menu ID in the menu resource.

function result: A handle to the menu structure for the menu. You can use the returned menu handle to refer to this menu in most Menu Manager functions. If GetMenu is unable to read the menu or menu definition function from the resource file, GetMenu returns nil.

DISCUSSION

In addition to creating a menu, the GetMenu function also creates a menu structure for the menu. GetMenu reads the menu definition function into memory (if not already present) and stores a handle to the menu definition function in the menu structure. GetMenu does not insert the newly created menu into the current menu list.

You typically use the GetMenu function only when you create submenus; you can create all your pull-down menus at once using the function GetNewMBar, and you can create pop-up menus using the standard pop-up menu button control definition function.

After reading the 'MENU' resource , GetMenu searches for an extended menu resource and an 'mctb' resource with the same resource ID as the 'MENU' resource. If the specified 'mctb' resource exists, GetMenu uses SetMCEntries to add the entries defined by the resource to the application’s menu color information table. If the 'mctb' resource does not exist, GetMenu uses the default colors specified in the menu bar entry of the application’s menu color information. If neither a menu bar entry nor a 'mctb' resource exists, GetMenu uses the standard colors for the menu.

Storing the definitions of your menus in resources (especially menu titles and menu items) makes your application easier to localize.

Menus in a resource must not be purgeable nor should the resource lock bit be set. Do not define a “circular” hierarchical menu—that is, a hierarchical menu in which a submenu has a submenu whose submenu is a hierarchical menu higher in the chain.

SPECIAL CONSIDERATIONS

To release the memory associated with a menu that you created using GetMenu, first call DeleteMenu to remove the menu from the current menu list and to remove any entries for this menu in your application’s menu color information table; then call DisposeMenu to dispose of the menu structure. After disposing of a menu, use DrawMenuBar to update the menu bar.

VERSION NOTES

This function was changed with Appearance Manager 1.0 to support the extended menu resource.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.